IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/librw/RWTValSet.z/RWTValSet

Text File | 2002-10-03 | 20.6 KB | 529 lines

RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))                                                RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))



NNNNaaaammmmeeee
     RWTValSet<T,C> - Rogue Wave library class

SSSSyyyynnnnooooppppssssiiiissss
              #include <rw/tvset.h>
          RWTValSet<T,C> s;



SSSSttttaaaannnnddddaaaarrrrdddd CCCC++++++++ LLLLiiiibbbbrrrraaaarrrryyyy DDDDeeeeppppeeeennnnddddeeeennnntttt!!!!



     RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt requires the Standard C++ Library.


DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
     This class maintains a collection of values, which are ordered according
     to a comparison object of type CCCC.  CCCC must induce a total ordering on
     elements of type TTTT via a public member
          bbbboooooooollll ooooppppeeeerrrraaaattttoooorrrr(((())))((((ccccoooonnnnsssstttt TTTT&&&& xxxx,,,, ccccoooonnnnsssstttt TTTT&&&& yyyy)))) ccccoooonnnnsssstttt which returns ttttrrrruuuueeee if
     xxxx should precede yyyy within the collection.  The structure lllleeeessssssss<<<<TTTT>>>> from the
     C++-standard header file <<<<ffffuuuunnnnccccttttiiiioooonnnnaaaallll>>>> is an example.  RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt<<<<TTTT,,,,CCCC>>>> will
     not accept an item that compares equal to an item already in the
     collection.  (RRRRWWWWTTTTVVVVaaaallllMMMMuuuullllttttiiiiSSSSeeeetttt<<<<TTTT,,,,CCCC>>>> may contain multiple items that compare
     equal to each other.)  Equality is based on the comparison object and not
     on the ======== operator.  Given a comparison object ccccoooommmmpppp, items aaaa and bbbb are
     equal if
          !!!!ccccoooommmmpppp((((aaaa,,,,bbbb)))) &&&&&&&& !!!!ccccoooommmmpppp((((bbbb,,,,aaaa)))).

PPPPeeeerrrrssssiiiisssstttteeeennnncccceeee
     Isomorphic.

EEEExxxxaaaammmmpppplllleeeessss
     In this example, a set of RRRRWWWWCCCCSSSSttttrrrriiiinnnnggggs is exercised.

              //



              // tvsstr.cpp
          //
          #include <rw/tvset.h>
          #include <rw/cstring.h>
          #include <iostream.h>
          #include <function.h>
          main(){
            RWTValSet<RWCString,less<RWCString> > set;
            set.insert("one");
            set.insert("two");
            set.insert("three");
            set.insert("one");     // Rejected: already in collection



                                                                        PPPPaaaaggggeeee 1111






RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))                                                RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))



            cout << set.entries() << endl;     // Prints "3"
            return 0;

RRRReeeellllaaaatttteeeedddd CCCCllllaaaasssssssseeeessss
     }


     Class RRRRWWWWTTTTVVVVaaaallllMMMMuuuullllttttiiiiSSSSeeeetttt<<<<TTTT,,,,CCCC>>>> offers the same interface to a collection that
     accepts multiple items that compare equal to each other.
     RRRRWWWWTTTTVVVVaaaallllMMMMaaaapppp<<<<KKKK,,,,TTTT,,,,CCCC>>>> maintains a collection of key-value pairs.  Class
     sssseeeetttt<<<<TTTT,,,,CCCC,,,,aaaallllllllooooccccaaaattttoooorrrr>>>> is the C++-standard collection that serves as the
     underlying implementation for RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt<<<<TTTT,,,,CCCC>>>>.

PPPPuuuubbbblllliiiicccc TTTTyyyyppppeeeeddddeeeeffffssss
              typedef set<T,C,allocator>                     container_type;



              typedef container_type::iterator               iterator;
          typedef container_type::const_iterator         const_iterator;
          typedef container_type::size_type              size_type;
          typedef T                                      value_type;
          typedef const T&                               const_reference;

PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss
              RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt<<<<TTTT,,,,CCCC>>>>(const C& comp = C());


     Constructs an empty set.

              RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt<<<<TTTT,,,,CCCC>>>>(const container_type& s);


     Constructs a set by copying all elements of ssss.

              RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt<<<<TTTT,,,,CCCC>>>>(const RWTValSet<T,C>& rws);


     Copy constructor.

              RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt<<<<TTTT,,,,CCCC>>>>
          (const T* first,const T* last,const C& comp = C());


     Constructs a set by copying elements from the array of TTTTs pointed to by
     ffffiiiirrrrsssstttt, up to, but not including, the element pointed to by llllaaaasssstttt.

PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr OOOOppppeeeerrrraaaattttoooorrrrssss
              RWTValSet<T,C>&
          ooooppppeeeerrrraaaattttoooorrrr====(const RWTValSet<T,C>& s);
          RWTValSet<T,C>&
          ooooppppeeeerrrraaaattttoooorrrr====(const container_type& s);



                                                                        PPPPaaaaggggeeee 2222






RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))                                                RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))



     Destroys all elements of self and replaces them by copying all elements
     of ssss....

              bool
          ooooppppeeeerrrraaaattttoooorrrr<<<<(const RWTValSet<T,C>& s) const;
          bool
          ooooppppeeeerrrraaaattttoooorrrr<<<<(const container_type& s) const;


     Returns ttttrrrruuuueeee if self compares lexicographically less than ssss, otherwise
     returns ffffaaaallllsssseeee.  Assumes that type TTTT has well-defined less-than semantics
     (TTTT::::::::ooooppppeeeerrrraaaattttoooorrrr<<<<((((ccccoooonnnnsssstttt TTTT&&&&)))) or equivalent).

              bool
          ooooppppeeeerrrraaaattttoooorrrr========(const RWTValSet<T,C>& s) const;
          bool
          ooooppppeeeerrrraaaattttoooorrrr========(const set<T,C>& s) const;


     Returns ttttrrrruuuueeee if self compares equal to ssss, otherwise returns ffffaaaallllsssseeee.  Two
     collections are equal if both have the same number of entries, and
     iterating through both collections produces, in turn, individual elements
     that compare equal to each other.

PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              void
          aaaappppppppllllyyyy(void (*fn)(const_reference,void*), void* d) const;


     Applies the user-defined function pointed to by ffffnnnn to every item in the
     collection.  This function must have prototype:





                 void yourfun(const_reference a, void* d);


     Client data may be passed through parameter dddd.

              iterator
          bbbbeeeeggggiiiinnnn();
          const_iterator
          bbbbeeeeggggiiiinnnn() const;


     Returns an iterator positioned at the first element of self.

              void
          cccclllleeeeaaaarrrr();




                                                                        PPPPaaaaggggeeee 3333






RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))                                                RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))



     Clears the collection by removing all items from self.  Each item will
     have its destructor called.

              bool
          ccccoooonnnnttttaaaaiiiinnnnssss(const_reference a) const;


     Returns ttttrrrruuuueeee if there exists an element tttt in self that compares equal to
     aaaa, otherwise returns ffffaaaallllsssseeee.

              bool
          ccccoooonnnnttttaaaaiiiinnnnssss(bool (*fn)(const_reference,void*), void* d) const;


     Returns ttttrrrruuuueeee if there exists an element tttt in self such that the
     expression ((((((((****ffffnnnn))))((((tttt,,,,dddd)))))))) is ttttrrrruuuueeee, otherwise returns ffffaaaallllsssseeee.  ffffnnnn points to a
     user-defined tester function which must have prototype:





                 bool yourTester(const_reference a, void* d);


     Client data may be passed through parameter dddd.

              void
          ddddiiiiffffffffeeeerrrreeeennnncccceeee(const RWTValSet<T,C>& s);
          void
          ddddiiiiffffffffeeeerrrreeeennnncccceeee(const container_type& s);


     Sets self to the set-theoretic difference given by ((((sssseeeellllffff ---- ssss)))).

              iterator
          eeeennnndddd();
          const_iterator
          eeeennnndddd() const;


     Returns an iterator positioned "just past" the last element in self.

              size_type
          eeeennnnttttrrrriiiieeeessss() const;


     Returns the number of items in self.

              bool
          ffffiiiinnnndddd(const_reference a, T& k) const;




                                                                        PPPPaaaaggggeeee 4444






RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))                                                RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))



     If there exists an element tttt in self that compares equal to aaaa, assigns tttt
     to kkkk and returns ttttrrrruuuueeee.  Otherwise, returns ffffaaaallllsssseeee and leaves the value of
     kkkk unchanged.

              bool
          ffffiiiinnnndddd(bool (*fn)(const_reference,void*), void* d, T& k) const;


     If there exists an element tttt in self such that the expression
     ((((((((****ffffnnnn))))((((tttt,,,,dddd)))))))) is ttttrrrruuuueeee, assigns tttt to kkkk and returns ttttrrrruuuueeee.  Otherwise,
     returns ffffaaaallllsssseeee and leaves the value of kkkk unchanged.  ffffnnnn points to a user-
     defined tester function which must have prototype:





                 bool yourTester(const_reference a, void* d);


     Client data may be passed through parameter dddd.

              bool
          iiiinnnnsssseeeerrrrtttt(const_reference a);


     Adds the item aaaa to the collection.  Returns ttttrrrruuuueeee if the insertion is
     successful, otherwise returns ffffaaaallllsssseeee.  The function will return ttttrrrruuuueeee
     unless the collection already holds an element with the equivalent key.

              void
          iiiinnnntttteeeerrrrsssseeeeccccttttiiiioooonnnn(const RWTValSet<T,C>& s);
          void
          iiiinnnntttteeeerrrrsssseeeeccccttttiiiioooonnnn(const container_type& s);


     Sets self to the intersection of self and ssss.

              bool
          iiiissssEEEEmmmmppppttttyyyy() const;


     Returns ttttrrrruuuueeee if there are no items in the collection, ffffaaaallllsssseeee otherwise.

              bool
          iiiissssEEEEqqqquuuuiiiivvvvaaaalllleeeennnntttt(const RWTValSet<T,C>& s) const;


     Returns ttttrrrruuuueeee if there is set equivalence between self and ssss, and returns
     ffffaaaallllsssseeee otherwise.





                                                                        PPPPaaaaggggeeee 5555






RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))                                                RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))



              bool
          iiiissssPPPPrrrrooooppppeeeerrrrSSSSuuuubbbbsssseeeettttOOOOffff(const RWTValSet<T,C>& s) const;


     Returns ttttrrrruuuueeee if self is a proper subset of ssss, and returns ffffaaaallllsssseeee
     otherwise.

              bool
          iiiissssSSSSuuuubbbbsssseeeettttOOOOffff(const RWTValSet<T,C>& s) const;


     Returns ttttrrrruuuueeee if self is a subset of ssss; ffffaaaallllsssseeee otherwise.

              size_type
          ooooccccccccuuuurrrrrrrreeeennnncccceeeessssOOOOffff(const_reference a) const;


     Returns the number of elements tttt in self that compare equal to aaaa.

              size_type
          ooooccccccccuuuurrrrrrrreeeennnncccceeeessssOOOOffff(bool (*fn)(const T&,void*),void* d) const;


     Returns the number of elements tttt in self such that the
     expression((((((((****ffffnnnn))))((((tttt,,,,dddd)))))))) is ttttrrrruuuueeee.  ffffnnnn points to a user-defined tester
     function which must have prototype:





                 bool yourTester(const_reference a, void* d);


     Client data may be passed through parameter dddd.

              bool
          rrrreeeemmmmoooovvvveeee(const_reference a);


     Removes the first element tttt in self that compares equal to aaaa and returns
     ttttrrrruuuueeee.  Returns ffffaaaallllsssseeee if there is no such element.

              bool
          rrrreeeemmmmoooovvvveeee(bool (*fn)(const_reference,void*), void* d);


     Removes the first element tttt in self such that the expression ((((((((****ffffnnnn))))((((tttt,,,,dddd))))))))
     is ttttrrrruuuueeee and returns ttttrrrruuuueeee.  Returns ffffaaaallllsssseeee if there is no such element.  ffffnnnn
     points to a user-defined tester function which must have prototype:





                                                                        PPPPaaaaggggeeee 6666






RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))                                                RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))







                 bool yourTester(const_reference a, void* d);


     Client data may be passed through parameter dddd.

              size_type
          rrrreeeemmmmoooovvvveeeeAAAAllllllll(const_reference a);


     Removes all elements tttt in self that compare equal to aaaa.  Returns the
     number of items removed.

              size_type
          rrrreeeemmmmoooovvvveeeeAAAAllllllll(bool (*fn)(const_reference,void*), void* d);


     Removes all elements tttt in self such that the expression ((((((((****ffffnnnn))))((((tttt,,,,dddd))))))))is
     ttttrrrruuuueeee.  Returns the number of items removed.  ffffnnnn points to a user-defined
     tester function which must have prototype:





                 bool yourTester(const_reference a, void* d);


     Client data may be passed through parameter dddd.

              set<T,C,allocator>&
          ssssttttdddd();
          const set<T,C,allocator>&
          ssssttttdddd() const;


     Returns a reference to the underlying C++-standard collection that serves
     as the implementation for self.  This reference may be used freely,
     providing access to the C++-standard interface as well as
     interoperability with other software components that make use of the
     C++-standard collections.

              void
          ssssyyyymmmmmmmmeeeettttrrrriiiiccccDDDDiiiiffffffffeeeerrrreeeennnncccceeee(const RWTValSet<T,C>& s);
          void
          ssssyyyymmmmmmmmeeeettttrrrriiiiccccDDDDiiiiffffffffeeeerrrreeeennnncccceeee(const container_type& s);


     Sets self to the symmetric difference of self and ssss.



                                                                        PPPPaaaaggggeeee 7777






RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))                                                RRRRWWWWTTTTVVVVaaaallllSSSSeeeetttt((((3333CCCC++++++++))))



              void
          UUUUnnnniiiioooonnnn(const RWTValSet<T,C>& s);
          void
          UUUUnnnniiiioooonnnn(const container_type& s);


     Sets self to the union of self and ssss.  Note the use of the uppercase
     "U"in UUUUnnnniiiioooonnnn to avoid conflict with the C++ reserved word.

RRRReeeellllaaaatttteeeedddd GGGGlllloooobbbbaaaallll OOOOppppeeeerrrraaaattttoooorrrrssss
              RWvostream&
          ooooppppeeeerrrraaaattttoooorrrr<<<<<<<<(RWvostream& strm, const RWTValSet<T,C>& coll);
          RWFile&
          ooooppppeeeerrrraaaattttoooorrrr<<<<<<<<(RWFile& strm, const RWTValSet<T,C>& coll);


     Saves the collection ccccoooollllllll onto the output stream ssssttttrrrrmmmm, or a reference to
     it if it has already been saved.

              RWvistream&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(RWvistream& strm, RWTValSet<T,C>& coll);
          RWFile&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(RWFile& strm, RWTValSet<T,C>& coll);


     Restores the contents of the collection ccccoooollllllll from the input stream ssssttttrrrrmmmm.

              RWvistream&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(RWvistream& strm, RWTValSet<T,C>*& p);
          RWFile&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(RWFile& strm, RWTValSet<T,C>*& p);


     Looks at the next object on the input stream ssssttttrrrrmmmm and either creates a
     new collection off the heap and sets pppp to point to it, or sets pppp to point
     to a previously read instance.  If a collection is created off the heap,
     then you are responsible for deleting it.


















                                                                        PPPPaaaaggggeeee 8888